home *** CD-ROM | disk | FTP | other *** search
/ The Learning Curve / The Learning Curve (Weird Science, 1996).iso / computers / guru3.0 / theguru / docs / guru.doc < prev    next >
Encoding:
Text File  |  1996-02-27  |  16.6 KB  |  463 lines
  1. This is the documentation of:
  2.  
  3. Program  : The Guru 3.00 (November 8, 1994)
  4. Language : Assembly
  5. Author   : Emiel Lensink
  6.  
  7. AUTHOR's NOTE: Personally I consider this document obsolete. It's here for
  8.  those few users that still use 1.3 machines. It hasn't been updated for
  9.  quite a while now, and I recommend anybody to read the guide file instead.
  10.  
  11.  
  12. DISCLAIMER:
  13.  
  14.  Although I (the author) have thoroughly tested 'The Guru' and have done
  15.  everything possible to make the progra reliable, you use it AT YOUR OWN
  16.  RISK! This software comes 'as is'; no warranties whatsoever. I am not
  17.  responsible for any damage caused by using this program, either direct
  18.  or indirect. If this program spontaneously low level formats your computer,
  19.  crashes your harddisk, blows your nose, or melts your neighbours, I AM
  20.  NOT RESPONSIBLE !!!
  21.  
  22.  
  23. DISTRIBUTION:
  24.  
  25.  'The Guru' is freely redistributable. You may give it to your friends, your
  26.  neighbours, to anybody you know and don't know. Spread the word AND the
  27.  disk! 'The Guru' may be includesd in PD libraries, on coverdisks, on CD's
  28.  etc. You may archive the files as long as they are unaltered after
  29.  dearchieving. The only restriction I make is that the program MAY NOT BE
  30.  SOLD FOR PROFIT, and that you keep all the files together. You should have
  31.  the following files:
  32.  
  33.     TheGuru(.info)                (drawer)
  34.       Guru3.0(.info)
  35.       Error.data(.info)
  36.       Docs(.info)                 (drawer)
  37.         Guru.guide(.info)
  38.         Guru.doc(.info)
  39.         Guru.iff(.info)
  40.  
  41.     General(.info)                (drawer)
  42.       SimErr(.info)
  43.       Faults(.info)
  44.       CrashZero(.info)
  45.  
  46.     MAGICons(.info)               (drawer)
  47.       Guru3.0.info
  48.                 
  49.     Sources(.info)                (drawer)
  50.       Guru30.s(.info)
  51.       Fault.s(.info)
  52.       CrashZero.s(.info)
  53.       SimErr.s(.info)
  54.       Gadgets.i(.info)
  55.       GuruLogo.i(.info)
  56.  
  57.  If your set is not complete I advise you not to use the program(s), because
  58.  of the possibility of viruses etc.
  59.  
  60.  
  61. POSTWARE:
  62.  
  63.  This program is postware. This means that if you like it and use the
  64.  program you should send me a postcard of your hometown or country.
  65.   
  66.  My address is:
  67.  Emiel Lensink
  68.  Notengaarde 33
  69.  3992JR Houten
  70.  Holland
  71.  
  72.  
  73. GENERAL GURU KNOWLEDGE:
  74.  
  75.  Every amiga owner has seen a guru message or software error as they are
  76.  called in kickstart 2.0 and above at least once in his/her life. That 
  77.  nasty red flashing box has a purpose; the two numbers in the box can tell
  78.  you why your amiga crashed. The numbers take the following form:
  79.  
  80.  +----------------------------------------------------------------------+
  81.  |     Software failure.        Press left mouse button to continue.    |
  82.  |                                                                      |
  83.  |                 Error: 12345678   Task: 87654321                     |
  84.  +----------------------------------------------------------------------+
  85.  
  86.  You see two numbers here, one behind error and one behind task.
  87.  The one behind task is the address in memory where the crash occurred.
  88.  You can use a monitor and/or dissassembler on that address to see the
  89.  instruction(s) that caused the error. The number behind error is the
  90.  real important one, it tells you precisely what error occurred.
  91.  
  92.  There are three basic types of guru-messages, both in recovery and
  93.  deadend types. 
  94.  
  95. 1- PROCESSOR EXCEPTIONS:
  96.  This is your 680x0 speaking to you. This occurs if the processor p.e.
  97.  doesn't understand an instruction.
  98.  
  99. 2- SPECIFIC ALERTS:
  100.  These are error codes generated by a specific subsystem of the OS.,
  101.  for example dos.library or graphics.library. This is the most frequent
  102.  occuring kind of error. Some programs generate their own GURU alerts,
  103.  but those are of course not included in the guru (cos I don't have 'em).
  104.  
  105. 3- GENERAL ALERTS:
  106.  The number consists of 4 parts (see diagram below) which together form
  107.  a longword. (32 bits)
  108.  
  109.         +-+-------+--------+-----------------+
  110.         |x|xxxxxxx|xxxxxxxx|xxxxxxxx xxxxxxxx|
  111.         +-+-------+--------+-----------------+
  112.          | |     | |      | |               |
  113. Bit(s): 31 30   24 23    16 15              0
  114.  
  115.  The meaning of this number is as follows:
  116.  
  117.  Bit     31: This decides whether a number is a DEADEND or a RECOVERY
  118.              alert. If bit 31 is not set, it's a RECOVERY alert, which
  119.              means that you should be able to resume work after clicking
  120.              the left mousebutton. This kind of alerts usually appears
  121.              in an orange flashing box. If bit 31 is set, you have a
  122.              DEADEND alert, which means that your computer will reboot
  123.              and you lose all your unsaved work. This type of alerts
  124.              usually shows up in a flashing red box.
  125.              (Note: On kick 1.2/1.3 ALL alerts show up in a red box,
  126.               and a recovery alert usually reboots your computer.) 
  127.  
  128.  
  129.  Bits 24-30: The amiga operating system is divided in diferrent subsystems
  130.              like dos, intuition, graphics, etc.. Every subsystem has
  131.              its own code. The number here tells you which part of the
  132.              operating system caused the crash.
  133.  
  134.  Bits 16-23: This number indicates what the operating system couldn't do,
  135.              causing it to crash. This usually indicates things like
  136.              OpenLibrary, CreateLib etc... 
  137.  
  138.  Bits 0-15 : This part tells you what couldn't be opened, loaded, checked
  139.              etc... This indicates another subsystem.
  140.  
  141.  
  142. An example: dos.library couldn't open timer.device.
  143.  
  144.  The subsystem code for dos.library is $07000000, the errorcode for 
  145.  OpenDevice is $00040000, and the code for timer.device is $00008015.
  146.  This is a rather serious error, so it'll probably a deadend alert, which
  147.  means bit 31 will be set ($80000000). The final alert number will be:
  148.  
  149.  $80000000 ! $07000000 ! $00040000 ! $00008015 = $87048015.
  150.  
  151.  (ps: try TheGuru on this number, it really works !!) 
  152.  
  153.  
  154. WHAT IS 'THE GURU':
  155.  
  156.  'The Guru' is a simple database for guru numbers, and dos error numbers.
  157.  It's mainly intended as a tool for (system friendly) programmers.
  158.  
  159.  
  160. WHY USE IT ?:
  161.  
  162.  Because it makes debugging your programs quite a lot easier, since after
  163.  every crash the OS finds out what went wrong, and tries to tell you using
  164.  a guru or software alert; just write down the number and enter it in 'The
  165.  Guru' for a description of what went wrong. No more tedious searching
  166.  in books or inconcise descriptions, 'The Guru' solves it all !!
  167.  
  168.  Beside that (and this is useful for EVERY amiga owner) 'The Guru' also 
  169.  offers help on dos error numbers. You'll probably have seen something like
  170.  'Couldn't load xxx, error 205'. Just enter this number in 'The Guru' and
  171.  instantaneously you know that '205' means 'Object not found'.
  172.  
  173.  Happy bughunting!!
  174.  
  175.  
  176. BIG DUMMIES GUIDE:
  177.  
  178. BUTTONS:
  179.  
  180.  Here's a quick description of the various buttons and slider in the 'The
  181.  Guru' window:
  182.  
  183.  LEFT 'SET'  : Activate the guru display. You can now change it's contents.
  184.  RIGHT 'SET' : Activate the dos display. You can now change it's contents
  185.  
  186.  LEFT/RIGHT '<' and '>' : Change the cursor position in the active display.
  187.                           (The cursor is the brightest digit.)
  188.  
  189.  'GURU'      : Find the description of the current guru number.
  190.  'LAST'      : Fetches the last guru number from the system.
  191.  
  192.  'DOS '      : Find the description of the current dos error number.
  193.  'DEFAULT'   : Sets everything to zero and shows the logo.
  194.  
  195.  'ABOUT'     : Shows very important information about the program.
  196.  'QUIT'      : Guess...
  197.  
  198. KEYS:
  199.  
  200.  'G'         : Pressing the 'g' key is equivalent to clicking the 'GURU'
  201.                button.
  202.  'O'         : Equivalent to the 'DOS' button.
  203.  '<' and ',' 
  204.  and '<-'    : Equivalent to '<' for the active display.
  205.  '>' and '.'
  206.  and '->'    : Equivalent to '>' for the active display.
  207.  
  208.  'L'         : Equivalent to the 'LAST' button.
  209.  'R'         : Equivalent to the 'DEFAULT' button.
  210.  'U'         : Equivalent to the 'ABOUT' button.
  211.  'Q'         : Equivalent to the Quit button.
  212.  
  213.  '[TAB]'     : Switches active displays
  214.  '[1] to [9] and [A] to [F] : Same as the numeric buttons.
  215.  
  216.  '[RETURN]'   : Gets the description for the active display.
  217.  
  218. Just for an example try typing this string in 'The Guru' : 'r80000005'[ENTER]
  219.  
  220.  
  221. CUSTOMISING:
  222.  
  223.  'The Guru' can be customized using tooltypes:
  224.  
  225.   AUTOFRONT :
  226.   The window pops to front as soon as it's activated.
  227.   (can be useful if the window is obscured by some other windows)
  228.  
  229.   TOPAZ :
  230.   The Guru is fully font sensitive, and uses the default screen font for
  231.   text and buttons. If you don't like this you can specify this tooltype
  232.   to force The Guru into using Topaz 8.
  233.  
  234.   PUBSCREEN=Screenname : 
  235.   The Guru can open it's window on any public screen 
  236.  
  237.   LANGUAGE=Filename :
  238.   Different languages are supported through language files. The exact
  239.   format of a language file is specified in the language section. 
  240.   If this tooltype is not specified, the default language (english)
  241.   will be used.
  242.  
  243.   DATAFILE=Filename :
  244.   Specifies the exact filename and optional path of the data file.
  245.   If this tooltype is not specified, the default will be used, namely
  246.   the file Error.data in the same directory as the The Guru program.
  247.  
  248.  
  249. LANGUAGES:
  250.  
  251.  The Guru uses language files for languages other than english.
  252.  If you want to make your own language file, here's how:
  253.  
  254.  A language file is just a simple ascii file in the following format:
  255.  (line numbers are for clarity, NOT for inclusion in a language file)
  256.  
  257. 1 : Short description of the file
  258. 2 : Who did it
  259. 3 : (not used)
  260. 4 : Text for 'SET' button
  261. 5 : Text for 'GURU' button
  262. 6 : Text for 'LAST' button
  263. 7 : Text for 'DEFAULT' button
  264. 8 : Text for 'DOS' button
  265. 9 : Text for 'ABOUT' button
  266. 10: Text for 'QUIT' button
  267. 11: (not used)
  268. 12: Text shown if data-file not found (1 line!)
  269. 13: Response text to 12
  270. 14: Text shown if data-file corrupt (1 line!)
  271. 15: Response text to 14
  272. 16: Key shortcut for 'GURU' button (1 character, no Amiga-X or so)
  273. 17: Key shortcut for 'LAST' button
  274. 18: Key shortcut for 'DEFAULT' button
  275. 19: Key shortcut for 'DOS' button
  276. 20: Key shortcut for 'ABOUT' button
  277. 21: Key shortcut for 'PRINT' button 
  278.  
  279.  NOTES: Keep the text for buttons SHORT.
  280.  
  281.  WARNING: Do not make a language file any longer or shorter than the specs
  282.  above; it may lead to corrupt text output!
  283.  
  284.  
  285. SYSTEM REQUIREMENTS:
  286.  'The Guru' should run on any amiga with at least kickstart 1.2 .
  287.  It has been successfully tested on the following configurations:
  288.  
  289.  A3000 : 2 Mb CHIP, 4 Mb FAST, Kickstart 2.04
  290.  A3000 : 2 Mb CHIP, - Mb FAST, Kickstart 1.3
  291.  A3000 : 2 Mb CHIP,14 Mb FAST, Kickstart 3.1
  292.  A500+ : 2 Mb CHIP, - Mb FAST, Kickstart 2.04
  293.  A500+ : 2 Mb CHIP, - Mb FAST, Kickstart 1.3
  294.  A500  :0.5Mb CHIP,0.5Mb FAST, Kickstart 1.2
  295.  A1200 : 2 Mb CHIP, - Mb FAST, Kickstart 3.0 
  296.  
  297.  The program has also proven to be 100% enforcer and mungwall proof.
  298.  (Note: 'The Guru' produces one enforcer hit when clicking the 'LAST'
  299.   button. I don't know if there's a non system-private field to read
  300.   for the last guru number; currently I just read a long from $100...)
  301.  
  302.  
  303. GURU HISTORY:
  304.  
  305. version 1.0  (July 28,1993) : - Real crap version with bugs...
  306.                               - Released at SHN
  307.  
  308. version 1.1  (Aug.  1,1993) : - Fixed all bugs (I guess)
  309.                               - Never really released
  310.  
  311. version 2.0  (Oct. 31,1993) : This is a complete recode...
  312.                               - Better user interface
  313.                               - Better descriptions
  314.  
  315. version 2.1  (Dec. 25,1993) : - Added customization by tooltypes in icon
  316.  
  317. version 2.2  (Jan.  ?,1994) : Fixed a bug - opened a font but didn't free it
  318.                               - Added zoom gadget in window
  319.  
  320. version 2.21 (Jan.  6,1994) : - Window is now NOCAREREFRESH (=300% faster)
  321.                               - Added RMBTRAP, just looks nicer
  322.  
  323. version 2.3  (Feb.  3,1994) : A lot of changes on this one...
  324.                               - Looks at screen palette for correct 3d
  325.                                 buttons. (The buttons looked inversed on 
  326.                                 a kick 1.3 machine with 2.0 color palette)
  327.                               - Changed the logo, looks nicer
  328.                               - Looks good on a 2-color workbench too !
  329.                                 (now all text is readable...)
  330.  
  331. version 2.4 to 2.6          : - Miscellaneous fixes and changes
  332.  
  333. version 2.7  (Apr.  ?,1994) : - Added PUBSCREEN tooltype
  334.                               - Fixed a bug in window centering
  335.  
  336. version 2.8  (Jul. 12,1994) : - Changed format of data files slightly
  337.                               - Improved searching routines somewhat
  338.  
  339. version 2.9  (Sep. 22,1994) : - Changed gadget rendering (8 color Wb)
  340.                               - Fixed a bug in the data files
  341.                               - Second public release !!
  342.  
  343. version 3.00 (Nov.  8,1994) : - Redesigned GUI
  344.                               - Fully font sensitive (even on 1.3)
  345.                               - Added a lot of new guru and dos errors
  346.                                 and descriptions.
  347.                               - Localizable (?) (even on 1.3)
  348.                               - Loads of other little things
  349.  
  350. version 3.01 (Jun. 25,1995) : - removed busy-loop in slider-handling
  351.                                 (now uses IDCMP_MOUSEMOVE to detect movement)
  352.  
  353. BUG REPORTS:
  354.  
  355.  If you find a bug in The Guru please let me know.
  356.  Write down EXACTLY what you were doing at the time the bug showed up,
  357.  your configuration, and anything else that might be relevant.
  358.  Also I'd like to know if you know about any guru-numbers not yet included
  359.  in The Guru.
  360.  
  361.  My address is:
  362.  Emiel Lensink
  363.  Notengaarde 33
  364.  3992 JR Houten
  365.  Holland
  366.  
  367.  I will not reply to any mail unless you include a self-addressed envelope
  368.  and (if you don't live in Holland) an 'international reply coupon'. These
  369.  can be optained at your local post office.
  370.  
  371.  
  372. THE FUTURE:
  373.  
  374.  In my opinion 'The Guru' is completely finished, and no further updates
  375.  are planned. (except for some translated versions)
  376.  If you have any suggestions however, I'll be glad to hear about them,
  377.  and maybe they will eventually be implemented. (with your name in the docs,
  378.  Oooooh)
  379.  
  380.  My address is in the 'bugs' section.
  381.  
  382.  
  383. THE SOURCE:
  384.  
  385.  Yes, it's included. It's included for instructional purposes only, the
  386.  only person allowed to release updates or new versions of 'The Guru' is
  387.  me. It probably won't even assemble, because I make extensive use of macro's
  388.  and custom includes.
  389.  
  390.  
  391. TECHNICAL SPECIFICATIONS:
  392.  
  393.  Program name    : The Guru 3.00
  394.  Author          : Emiel Lensink
  395.  Language        : 100% highspeed assembly
  396.  
  397.  Features        : - 101% operating system friendly
  398.                    - runs on all amiga's
  399.                    - looks pretty nice
  400.                    - written by me
  401.                    - can be configured
  402.                    - fully font sensitive
  403.                    - localizable
  404.                    - smooth scrolling text window
  405.                    - fast
  406.                    - can open on any public screen
  407.                    - written for only the Amiga
  408.                    - only 17204 bytes big
  409.  
  410.  Add-ons         : - multiple language files (to be released)
  411.  
  412.  'The Guru' was developed using the following equipment & software:
  413.  - A3000 , 2Mb CHIP, 14 Mb FAST, running kickstart 3.1
  414.  - Piccolo graphics board (better than AGA)
  415.  - Personal Paint
  416.  - Hisoft Devpac 3.04
  417.  - The Ultimate Graphics convertor (my own product, never finished)
  418.  - Enforcer & mungwall
  419.  - 3M & TDK floppy disks
  420.  
  421.  
  422. NOTE TO KICKSTART 1.3 USERS:
  423.  
  424.  'The Guru' 3.00 is still 1.3 compatible, but this is merely a patch of
  425.  some routines. Some features simply don't work, and I'm not going to
  426.  fix it; you fix it: UPGRADE !!
  427.  
  428.  The features not available are:
  429.  - Can't open on public screens (you don't even have them...)
  430.  - No zoom button
  431.  - Amigaguide docs may or may not work
  432.  - No error requesters (you don't have EasyReqArgs...)
  433.  - All tooltypes must end with '=' so 'AUTOFRONT' must be 'AUTOFRONT='
  434.  - Not very thoroughly tested
  435.  
  436.  Now don't write any complaining letters or so because I definitely
  437.  have stopped coding for 1.3 machines! Why don't you realise that you are
  438.  holding back AMIGA development; 1.3 compatible programs look crippled
  439.  when compared to their 2.0 only counterparts! Don't say '... but 1.3 does
  440.  everything I want it to do...'. Yeah, right... Be nice to your Amiga,
  441.  UPGRADE. 2.0 roms are available for next to nothing nowadays. UPGRADE.
  442.  
  443.  
  444. CRASHZERO:
  445.  
  446.  This is a very small program which causes your computer to crash with a
  447.  'Division by zero' alert. It was used during the development of 'The Guru'
  448.  for test purposes. Now that 'The Guru' is finished, this program is 
  449.  completely useless.
  450.  
  451.  
  452. SIMERR:
  453.  
  454.  This program generates a recovery alert. After this program has run, you
  455.  can click the 'LAST' button in 'The Guru' to retrieve the number shown in
  456.  the recovery alert. This program was made for test purposes only.
  457.  
  458.  
  459. FAULTS:
  460.  
  461.  This is a small cli-only program. It lists all the dos error codes in
  462.  your rom. It was made to find any undocumented dos error numbers.
  463.